home *** CD-ROM | disk | FTP | other *** search
/ Aminet 49 / Aminet 49 (2002)(GTI - Schatztruhe)[!][Jun 2002].iso / Aminet / util / rexx / ral3p7a.lha / docs / rexxarplib.doc
Text File  |  2000-04-10  |  60KB  |  1,259 lines
  1. +----------------------------------------------------------------------+
  2. |                                                                      |
  3. |                  D I S C L A I M E R   N O T I C E                   |
  4. |                                                                      |
  5. |  This document and/or  portions of the material and  data furnished  |
  6. |  herewith,  was developed under sponsorship of the U.S. Government.  |
  7. |  Neither the U.S.  nor  the U.S.D.O.E.,  nor  the  Leland  Stanford  |
  8. |  Junior University, nor their employees,  nor their respective con-  |
  9. |  tractors, subcontractors, or their employees, makes  any warranty,  |
  10. |  express or implied, or assumes any liability or responsibility for  |
  11. |  accuracy,  completeness or  usefulness of any information, appara-  |
  12. |  tus, product or process disclosed, or represents that its use will  |
  13. |  not infringe privately-owned rights.  Mention of any product,  its  |
  14. |  manufacturer, or suppliers shall not, nor is it intended to, imply  |
  15. |  approval, disapproval, or fitness for any particular use. The U.S.  |
  16. |  and  the University at all times  retain the right to use and dis-  |
  17. |  seminate same for any purpose whatsoever.                           |
  18. |                                                                      |
  19. +----------------------------------------------------------------------+
  20.  
  21.  
  22.                     RexxArpLib.Library Version 3.5
  23.                     ==============================
  24.  
  25.                                 by
  26.  
  27.                           W.G.J. Langeveld
  28.                  Stanford Linear Accelerrator Center
  29.  
  30.              Copyright (C) 1988, 1989, 1990, 1992, 1993, 1994
  31.            The Trustees of the Leland Stanford Junior University
  32.  
  33.                         All Rights Reserved
  34.  
  35.                               Revised by
  36.  
  37.                               Joanne Dow
  38.                            Wizardess Designs
  39.                               June, 1998
  40.                               April, 2000
  41.  
  42. Version 3.7:    JD
  43. ------------
  44.  
  45.     This version adds two entry points and optional function prefixes.
  46. The functions SetPubScreenMode() and GetDefPublicScreen() have been added
  47. to allow additional screen manipulation for public screens, whether or not
  48. they were opened by rexxarplib.library. And any function name will also
  49. be matched when preceeded by "RALP_". This RALP_GetDefPublicScreen() will
  50. work the same as GetDefPublicScreen().
  51.  
  52. Version 3.6:    JD
  53. ------------
  54.  
  55.     This version is precisely the same as 3.5 except it was compiled
  56. with SAS C 6.58 and includes the sources.
  57.  
  58.     Source is available for this distribution. Christian A. Weber's
  59. iff.library include "iff.h" from his version 22.1 is included. (Within
  60. the rexxarplib.library source there are some defines needed to remain
  61. compatible with the older iff.library versions that rexxarplib has
  62. supported in the past. Rexxarplib was not changed to use newer calls.)
  63. A revised SAS C libinit.c is included with permission from Mr. James
  64. Cooper of SAS. Some of the changes affect compiler warnings. The first
  65. one corrects an apparent typo in the distributed source and must be
  66. included.
  67.  
  68.     Note that a portion of the source is Willy's "simple request" lib
  69. source. Also note that subordinate to that is an "inc" directory. This
  70. should be placed on your "include:" path when compiling both sreqr.lib
  71. and rexxarplib.library.
  72.  
  73. Version 3.5:    JD
  74. ------------
  75.  
  76.     This version of rexxarplib is compiled with SAS C 6.57. It
  77. incorporates the ASL requester fixes from version 3.4 and filelists.
  78. The source has been modified to use ANSI calling sequences throughout.
  79. All flagged compile time warnings that exist are determined to be
  80. benign. All references to screenshare.library have been removed as has
  81. all capability to operate on OS versions below 2.04.
  82.  
  83.     The screen handling had some errors in pen designation which have
  84. been corrected. You get predictable results now when you specify a
  85. short pen array. The pens specified are set and the others remain with
  86. the default settings. And attempting to open a screen that already
  87. exists is now safe. The old code fell through an AmigaDOS CloseScreen()
  88. call which could lead to undesireable results. You can still call the
  89. rexxarplib CloseScreen on a screen you did not open. Be careful.
  90.  
  91.     Distributed only as the single rexxarplib.library file.
  92.  
  93. Version 3.4:    JD
  94. ------------
  95.  
  96.     Internal version used for porting from SAS C 5.10b to SAS C 6.5.
  97. It was briefly posted on BIX for testing. It incorporated a fix to
  98. allocate large strings in the filreq.c and filelist.c routines using a
  99. pointer on the stack rather than allocating the entire variable space
  100. on the stack. The former technique caused stack overflows when used on
  101. Picasso 96 and I suspect other graphics software. It is superceded by
  102. version 3.5.
  103.  
  104. Version 3.3:
  105. ------------
  106.  
  107.     This version of rexxarplib is released mainly because there is no
  108. reason not to. It doesn't add much beyond version 3.0.
  109.     The major new thing is a moderately useful List requester
  110. (see RequestList).
  111.     Also, a few small bugs were fixed. Under 2.0x and up,
  112. screenshare.library is now truely no longer needed - before, it would mess
  113. up some of the 3-D look if screenshare.library was not present even under
  114. 2.0.
  115.     Another function that always was present is now documented:
  116. SendParsed, which is sometimes useful.
  117.     This may be the last version of rexxarplib to be released.
  118.  
  119.         20 April 1994, WGL
  120.  
  121. Version 3.0:
  122. ------------
  123.  
  124.     This version of rexxarplib makes use of a lot of AmigaDOS 2.0
  125. features and has various bugs fixed and a few other enhancements. Yet, it is
  126. smaller than previous versions because it is now completely compiled using
  127. SAS/C version 5.10a.
  128.     Under AmigaDOS 2.0, rexxarplib will now use the ASL file requester
  129. rather than the ARP one. The GetFile() function acquired some new arguments
  130. in order to allow you to use most of the features of the ASL requester (such
  131. as specifying its size and adding pattern gadgets or setting it up as a
  132. directory requester or using multiple select). *NOTE*. Various features of
  133. the ASL file requester only work correctly under versions of AmigaDOS
  134. *after* 2.02. Some features may not appear to work at all in early versions
  135. of 2.0, one of them is the "NOFILES" option. If you definitely *want* to use
  136. the ARP file requester, you can, by specifying a flag.
  137.     There is a new function called GetFont() which brings up the new
  138. ASL font requester. It too has lots of options and arguments. The SetFont()
  139. function never worked correctly but should now be fixed. It has also acquired
  140. a few more arguments, to go with the font requester.
  141.     Furthermore, under AmigaDOS 2.0, you should no longer need
  142. screenshare.library (at least not for rexxarplib.library - other programs may
  143. still require it!). It uses 2.0 public screens everywhere. This also means
  144. that you can use rexxarplib functions to operate on other applications'
  145. screens (if they are AmigaDOS 2.0 public ones). Applications that still open
  146. screenshare shared screens are still supported: if screenshare.library is
  147. available and a requested public screen does not exist as a 2.0 public
  148. screen, rexxarplib will try to find a screenshare-style screen of that name.
  149. Under AmigaDOS 1.3, rexxarplib of course uses screenshare.library exclusively.
  150. Support was also added for the long missing BACKDROP flag to OpenWindow.
  151.     Rexxarplib.library uses as much as possible the 2.0 3-D look, though
  152. there are cases where it decides (based on the colors for example) to use a
  153. slightly different rendering. In order to support more of the new 2.0
  154. features, the number of arguments to OpenScreen has been increased. You can
  155. now specify the width and height, as well as the coordinates of the top-left
  156. corner, and you can give it AutoScroll and Overscan flags. You can make
  157. as large a screen as AmigaDOS 2.0 allows and scroll around for example. Also,
  158. a MoveScreen() function was added to allow moving screens around from ARexx.
  159.     Under 2.0 you can now specify "Workbench" as a Public Screen Name.
  160. This means that some functions (such as ScreenColor()) will now also work for
  161. the Workbench. For some reason, ShowTitle() does not which is just as well
  162. anyway.    The number of arguments to ScreenColor() was increased so you can set
  163. the colors of a screen without having to open a window on it and you can also
  164. determine the colors of the screen using this function.
  165.     This version has new Getenv() and Setenv() functions. These functions
  166. are now compatible with the 2.0 environment variable system and use the
  167. GetVar, SetVar and DeleteVar routines. If GetVar fails, it will fall back
  168. to the ARP Getenv function. Under 1.3, the behavior is the same as before.
  169.     There is a new flag argument with AddGadget() for string gadgets.
  170. One possible flag is RIDGEBORDER. This causes string gadgets to have the
  171. "standard" 2.0 three-dimensional border. This is not the default, because
  172. this type of border requires a little more space and might break ARexx
  173. programs that assume the size is as before. Another flag was added to
  174. allow the gadget to be defined as a NUMERIC gadget.
  175.     Other than that, gadgets on two-color screens should now have visible
  176. gadget borders (by default - it is still possible to change them) and the
  177. colors should default to the proper values for the screen the window opens
  178. up on. Note that under 2.0 the colors your application comes up with may
  179. be a little different from what you would have expected. You can adjust the
  180. colors by using the SetReqColor() function.
  181.     Bugs fixed: the Flood() routine ran *very* slowly because it didn't
  182. have a TmpRas. Now, a TmpRas is allocated before the Flood operation is
  183. actually done, and the function is orders of magnitude faster. This actually
  184. used to work correctly in an earlier version of rexxarplib but broke in one
  185. of the more recent ones. Under AmigaDOS 1.3 the colors that some requesters
  186. used could be random in certain conditions. The createhost function didn't
  187. check correctly whether there were any messages it had sent out that were not
  188. yet replied to before closing down. The FileList function used a construct
  189. that was not reentrant. A minor problem in PostMsg() was also fixed. A little
  190. bug in AddGadget was fixed which could potentially cause enforcer hits if
  191. certain arguments were left unspecified. All these should be fixed.
  192.     Many thanks to the various beta testers - you know who you are!
  193.  
  194.     25 April 1991, WGL
  195.  
  196.  
  197. Version 2.52:
  198. -------------
  199.  
  200.     This release was necessary to fix problems with AmigaDOS 2.0
  201. shared screens. As of version 1.45, screenshare.library supports 2.0-style
  202. shared screens, but the previous versions of rexxarplib contained code that
  203. would prevent some functions to work with such screens because they have
  204. slightly different properties. Do not forget to install the new
  205. screenshare.library in libs:.
  206.  
  207.     16 October 1990, WGL
  208.  
  209.  
  210. Version 2.5:
  211. ------------
  212.  
  213.     Minor update. Two bugs in the FileList function were fixed: the third
  214. argument wouldn't work right if there was a fourth, and the Noexpand option was
  215. broken in the previous version. A problem in the documentation of some of the
  216. screen functions (ScreenRows/Cols/Lace/Color/ToBack/ToFront) was corrected. A
  217. ShowTitle function was added. The CreateHost function was modified, such that if
  218. the named public screen does not exist, the window will open on the WorkBench.
  219. Under 2.0, rexxarplib's screens now get the "3D" look. Some other esthetical
  220. problems with 2.0 were also fixed.
  221.  
  222.     22 August 1990, WGL
  223.  
  224.  
  225. Version 2.42 (internal release):
  226. -------------------------------
  227.  
  228.     Another minor update. The PostMsg() code was fixed for two little bugs:
  229. (1) when calling PostMsg() in rapid sequence from different ARexx programs, it
  230. was possible to wind up with an orphaned PostMsg window that would never go
  231. away; (2) after updating an existing PostMsg() window on a shared custom screen,
  232. it was impossible to ever close that screen.
  233.     The Area... functions have been completely rewritten. While they used to
  234. be simple interfaces to the AmigaDOS equivalents, they are no longer, although
  235. they still use the AmigaDOS functions down below. Advantages: areafills are now
  236. clipped against the window borders, there are 16 specific pattern fills and 125
  237. dithering patterns, the fills no longer take up as much memory as they used to,
  238. and the probability of a system crash with these functions is considerably
  239. reduced. "Problems": AreaEnd() now has an optional argument and SetOPen is now
  240. obsolete (See AreaEnd()), and fills involving areacircles and areaellipses that
  241. don't fit inside the window may now fail and only produce the outline of the
  242. fill.
  243.     Other minor changes: ScreenToFront/Back now return 0 when the screen
  244. doesn't exist, rather than signalling an error. Windows no longer have their
  245. minimum size set to their original size, so you can use sizing gadgets to
  246. make windows smaller too. Boolean gadgets now also have their GADGIMMEDIATE
  247. flag set, so that GADGETDOWN messages are actually possible now. Note, that
  248. when you request to receive both GADGETUP and GADGETDOWN messages, each
  249. gadget will report to you its message string *twice*. They can be distinguished
  250. by including %l in the message string, so that you can parse on UP vs. DOWN.
  251. The OpenScreen() function acquired another flag, TRUNCATE. See the description
  252. of OpenScreen(). A few little bugs were fixed in IFFImage. Note: iff.library
  253. apparently still has some bugs. It may still cause crashes of the machine when
  254. used with DPaint brushes. When in doubt, use full IFF pictures. Send mail to
  255. Chris Weber to have it fixed...
  256.     And finally, the entire code was carefully checked and improved to avoid
  257. crashes under low-memory situations.
  258.  
  259.     21 January 1990, WGL
  260.  
  261.  
  262. Version 2.3:
  263. -------------
  264.  
  265.     Minor update. A new option was added to FileList to inhibit expansion of
  266. file names where not wanted. DrawCircle apparently never worked, can't believe
  267. noone noticed: it is fixed now. A small bug in the simple requester code was
  268. found and fixed, as well as a few similar ones in the file requester interface
  269. code. Finally: the 'version' command will now properly display the version
  270. number of rexxarplib and rexxmathlib.
  271.  
  272.     20 May 1989, WGL
  273.  
  274.  
  275. Version 2.2a:
  276. -------------
  277.  
  278.     A small bug fix in IffImage().
  279.  
  280.     5 April 1989, WGL
  281.  
  282.  
  283. Version 2.2:
  284. ------------
  285.  
  286.     New in version 2.2 is an extension to the FileList() function. It can
  287. now expand the file names to include the full path, by supplying another
  288. argument. It will now also return the number of files in the .0 field of the
  289. stem variable, to make it more similar to ExecIO. A bug was fixed...
  290.     Also, version 2.2 now uses ARP's Getenv and Setenv calls, so that with
  291. ARP 1.3 you can use environment variables in the ENV: directory.
  292.     Another addition is a new option for IFFImage() allowing one to load
  293. images without changing the screen's colors.
  294.     Missing from the documentation so far has been that rexxarplib.library
  295. *requires* the presence of screenshare.library and diskfont.library in your
  296. current libs: directory. Several reports about library functions only returning
  297. error 12 have been due to these libraries not being present.
  298.     There was also a mistake in the documentation. The function that used
  299. to be listed as FreeMenu() is really called RemoveMenu().
  300.     The behavior of GetEnv() was changed by popular request. It will no
  301. longer generate an error when the argument is not an existing env variable.
  302. Instead it will return an empty string.
  303.  
  304.     20 February 1989, 8 March 1989, WGL
  305.  
  306. Version 2.1:
  307. ------------
  308.  
  309.     New in version 2.1 are the general function ScreenColor, and the
  310. CreateHost-related functions ReadHost, SetGadget and IFFImage. The allowed
  311. flag for AddItem and AddSubItem is now a specific one (this is an "incompatible"
  312. change). CloseWindow now allows the host to stay around through a second
  313. argument. The window flag DELTAMOVE was added for OpenWindow, and the window
  314. location is now available in reports (%e and %f).
  315.     The function IFFImage needs some explanation. It allows you to display
  316. (a portion of) an IFF image in your CreateHost window. For the time being, this
  317. function makes use of the iff.library written by Christian Weber. However, there
  318. is a suspicion that this library may cause the occasional system crash, and it is
  319. known that DPaint-style brushes are not supported. Only straight IFF picture
  320. files are known to work more or less reliably. At some point I intend to use
  321. something else.
  322.  
  323. Version 2.0:
  324. ------------
  325.  
  326.     Originally, this library was supposed to be an ARexx interface to the
  327. ARP library. However, although it indeed interfaces to some of the ARP
  328. functions, it has become much more of an interface to various Intuition
  329. functions. I have considered renaming the library to something else, but by now
  330. everyone refers to it by this name, so I'll leave it like it is.
  331.     Version 2.0 is pretty much the final version. The library has grown
  332. considerably since the first release, and it is about as big as a library should
  333. ever get. If I find the need for a lot of other functions, they'll have to go
  334. into a different library.
  335.     The library contains over 50 functions now. One is Charlie's famous ARP
  336. file requester, another is a simple combination string/boolean requester that
  337. does auto-everything. All you have to do is specify the strings you want it to
  338. display. Then there are environment variable things, and a simple message window
  339. you can keep hanging around. On popular request, there is now a wildcard
  340. expander (not to be confused with a 'directory' function!) that uses the new Rexx
  341. Variables Interface (RVI).
  342.     The major new things though, are the interface routines to Intuition.
  343. You can now open screens and windows, add boolean and string gadgets to them as
  344. well as menus, draw lines and areas and circles and whatever. You can make your
  345. gadgets, menus, and windows send messages to wherever you like and you can
  346. format those messages, though they have to ARexx messages, in any way you like,
  347. using any information that's currently available. All this is rather hard to
  348. explain. You'll really have to play with it and look at some examples.
  349.     As usual, this stuff is NOT public domain, but freely distributable.
  350.  
  351.     So have fun!
  352.  
  353.     Willy.
  354.  
  355.  
  356.  
  357. The functions are listed below.
  358. --------------------------------------------------------------------------------
  359.  
  360. GetFile
  361. =======
  362.  
  363.     Calling sequence:
  364.  
  365.     result = GetFile(x, y, pathname, filename, hailstring, publicscreen,
  366.                          options, stemname, width, height, pattern)
  367.  
  368.     x            = x coordinate of top-left corner of requester.
  369.     y            = y coordinate of top-left corner of requester.
  370.     pathname     = Default path name, first path name to be searched.
  371.         filename     = Default file name.
  372.         hailstring   = User instruction string.
  373.         publicscreen = Name of a public screen (optional).
  374.  
  375.     Under 2.0, we use ASL and the following arguments are recognized:
  376.         options      = One or more of:
  377.                        NOFILES        Directory requester
  378.                        PATGAD         Add a pattern gadget
  379.                        SAVE           "Save" requester (different color)
  380.                        MULTISELECT    Enable multiple selections. This
  381.                                       option requires the presence of the
  382.                                       name of a stem variable (see next)
  383.                                       or else this option is ignored.
  384.                        MATCHDIRS      Pattern in filename applies to dirs too.
  385.                        DOARP          Use the ARP requester instead.
  386.         stemname     = Name of a stem variable to receive the result.
  387.         width        = Preferred width of the requester
  388.         height       = Preferred height of the requester
  389.         pattern      = Default pattern.
  390.  
  391.         result       = See below.
  392.  
  393.     All arguments are optional, but the order is fixed. Therefore if only
  394. the second or third argument is specified, it needs to be prefixed by
  395. sufficient commas.
  396.     The selected path concatenated with the selected file name are
  397. returned as 'result' unless the stemname is specified. If the stemname is
  398. specified, the result will always be given in the form of a stem variable:
  399. stemname.0 will contain the number of returned file names, and stemname.i
  400. with i = 1 through stemname.0 will contain the file names. The 'result'
  401. will be set to the number of files returned. In addition, stemname.Width,
  402. stemname.Height, stemname.TopEdge and stemname.LeftEdge will contain the
  403. last used size and position of the file requester. If PATGAD is specified
  404. among the options, stemname.Pattern will contain the (possibly modified)
  405. pattern.
  406.     About patterns: there are two ways to make the file requester
  407. only list files that match a certain pattern. The pattern may be specified
  408. as part of default directory argument or as the default pattern argument
  409. if PATGAD is specified as an option. The pattern present in the default
  410. directory specification will not be displayed anywhere, even if the PATGAD
  411. option is used and a pattern gadget is provided. Yet, only files matching
  412. the pattern will be shown. If PATGAD is used together with a pattern
  413. in the default pattern argument, the requester will show only the files
  414. that match that pattern, and that pattern itself will be shown in the
  415. pattern gadget. If there is both a pattern in the default directory and
  416. the default pattern arguments, then all files must match both patterns.
  417. However, this last restriction is only present as neither the directory
  418. nor the pattern gadget contents are modified.
  419.     The result is not necessarily an existing file. It is up to the user
  420. to ascertain that the result is suitable for his purposes. If the user hits
  421. "CANCEL", the result is an empty string and/or stemname.0 = 0. It is also
  422. possible for the user to enter a pattern in the File gadget. Such a pattern
  423. is not expanded, and returned as a file name.
  424.     Notice that another way the result comes out to be empty is when the
  425. user leaves the requester hitting "OKAY" when both the path and file string
  426. gadgets are empty.
  427.     If 'publicscreen' is specified, the function will try to find the screen
  428. of that name. If it is set up properly, the requester will open on that
  429. screen. If not, the requester will appear on the Workbench. Under AmigaDOS
  430. 1.3, screenshare.library is used for this purpose. Under AmigaDOS 2.0
  431. a "public" screen of that name will be looked for and if this fails,
  432. screenshare.library is used, if it is in libs:.
  433.  
  434. GetFont
  435. =======
  436.  
  437.     This function is AmigaDOS 2.0-only.
  438.  
  439.     Calling sequence:
  440.  
  441.     result = GetFont(x, y, fontname, fontsize, hailstring, publicscreen,
  442.                          options, stemname, minheight, maxheight,
  443.                          fontstyle, fontflags, frontpen, backpen)
  444.  
  445.     x            = x coordinate of top-left corner of requester.
  446.     y            = y coordinate of top-left corner of requester.
  447.     fontname     = Default font name, first font to be displayed.
  448.         fontsize     = Default font size.
  449.         hailstring   = User instruction string.
  450.         publicscreen = Name of a public screen (optional).
  451.         options      = One or more of:
  452.                        BACKPEN       Allow selection of background pen
  453.                        DRAWMODE      Allow selection of drawing mode
  454.                        FIXEDWIDTH    Only allow fixed-width fonts
  455.                        FRONTPEN      Allow selection of foreground pen
  456.                        STYLE         Allow selection of style attributes
  457.         stemname     = Name of a stem variable to receive the result.
  458.         minheight    = Minimum allowable font height.
  459.         maxheight    = Maximum allowable font height.
  460.         fontstyle    = Initial font style
  461.         fontflags    = Initial font flags
  462.         frontpen     = Initial front pen
  463.         backpen      = Initial back pen
  464.  
  465.     result       = See below.
  466.  
  467.     All arguments are optional, but the order is fixed. Therefore if only
  468. the second or third argument is specified, it needs to be prefixed by
  469. sufficient commas.
  470.     The selected font, concatenated with a "/" and the selected size is
  471. returned as 'result' unless the stemname is specified. If the stemname is
  472. specified, the result will always be given in the form of a stem variable:
  473.         stemname.Name     = font name
  474.         stemname.YSize    = vertical size of font
  475.         stemname.Style    = style flags for font (see SetFont())
  476.         stemname.Flags    = font flags           (see SetFont())
  477.         stemname.FrontPen = foreground pen
  478.         stemname.BackPen  = background pen
  479.         stemname.DrawMode = drawing mode (JAM1, JAM2, COMPLEMENT)
  480. In this case, 'result' will be just the font name if a selection was made.
  481.     Notice, that the result is not necessarily an existing font. It is
  482. up to the user to ascertain that the result is suitable for his purposes. If
  483. the user hits "CANCEL", the 'result' is an empty string.
  484.     Notice that another way the result comes out to be empty is when the
  485. user leaves the requester hitting "OKAY" when both the font and size string
  486. gadgets are empty. In this case, though, the stem variable may still contain
  487. the last selected or default values for items other than the name and size.
  488.     If 'publicscreen' is specified, the function will try to find the screen
  489. of that name. If it is set up properly, the requester will open on that screen.
  490. If not, the requester will appear on the Workbench. Under AmigaDOS 2.0 (this
  491. function only works under AmigaDOS 2.0) a "public" screen of that name will be
  492. looked for and if this fails, screenshare.library is used, if it is in libs:.
  493.     This function requires the presence of diskfont.library in libs:.
  494.  
  495. Request
  496. =======
  497.  
  498.     Calling sequence:
  499.  
  500.     result = Request(x, y, prompts, string, okaytext, canceltext, publicscreen)
  501.  
  502.     x             = x coordinate of top-left corner of requester.
  503.     y             = y coordinate of top-left corner of requester.
  504.         prompts       = A string which will be displayed above any gadgets.
  505.                         Any embedded '\' characters will be treated as a line
  506.                         break.
  507.         string        = The default string to be displayed in a string gadget.
  508.                         If omitted, no string gadget will be provided.
  509.     okaytext      = The text to be used for an Okay gadget.
  510.                     If omitted, no okay gadget will be provided.
  511.     canceltext    = The text to be used for a Cancel gadget.
  512.                     If omitted, no cancel gadget will be provided.
  513.         publicscreen  = Name of a public screen (optional).
  514.  
  515.     All arguments are optional, but the order is fixed. Therefore if
  516. only the second or third argument is specified, it needs to be prefixed by
  517. sufficient commas.
  518.     If a string gadget is present, but no okay gadget, the string
  519. will be returned after modification by the user in result when the user
  520. hits <return>.
  521.     If both a string gadget and an okay gadget are present, the string
  522. will be returned in result only when the user clicks on the okay gadget.
  523.     If no string gadget is present, clicking of the okay gadget (if
  524. present) will cause the return in result of the string "OKAY".
  525.     In any case, if the user clicks either the cancel gadget or the
  526. close gadget, an empty string will be returned. Notice that another way the
  527. result comes out to be empty is when the user leaves the requester hitting
  528. "OKAY" when the string gadget is empty.
  529.     If 'publicscreen' is specified, the function will try to find the screen
  530. of that name. If it is set up properly, the requester will open on that
  531. screen. If not, the requester will appear on the Workbench. Under AmigaDOS
  532. 1.3, screenshare.library is used for this purpose. Under AmigaDOS 2.0
  533. a "public" screen of that name will be looked for and if this fails,
  534. screenshare.library is used, if it is in libs:.
  535.  
  536.  
  537. RequestList
  538. ===========
  539.  
  540.     Calling sequence:
  541.  
  542.     result = RequestList(start, end, list, x, y, w, h, publicscreen, flags)
  543.  
  544.         start         = member number of list where display starts
  545.         end           = member number of list where display ends
  546.         list          = stem variable that holds the members to be displayed
  547.     x             = x coordinate of top-left corner of requester.
  548.     y             = y coordinate of top-left corner of requester.
  549.         w             = width of requester
  550.         h             = Height of requester
  551.         publicscreen  = Name of a public screen (optional).
  552.         flags         = flags.
  553.  
  554.     The first three arguments are required. All others are optional, but
  555. the order is fixed.
  556.     The stem variable is assumed to be of the form variable.i with i
  557. an integer number. It is usual that variable.0 contains the size of the
  558. list, and the members are variable.1, variable.2 etc. The list requester will
  559. display all the members starting with variable.start and ending with variable.end.
  560.     The only flag recognized is "SORT". If specified, the list will be
  561. sorted before display.
  562.     If 'publicscreen' is specified, the function will try to find the screen
  563. of that name. If it is set up properly, the requester will open on that
  564. screen. If not, the requester will appear on the Workbench.
  565.     This function works only under AmigaDOS 2.0x and up.
  566.  
  567. PostMsg
  568. =======
  569.  
  570.     This function sets up a window with text. It returns immediately to
  571. the caller. Subsequent calls will erase lines and fill them with new text.
  572. If a line has zero length, the line will NOT be erased. This has the advantage
  573. that you can change the text in a line without redisplaying text in another
  574. line. It has the disadvantage that in order to erase lines, you have to
  575. specify at least a single space for each line you want to erase.
  576. The window will remain open, until a call is made with too few arguments.
  577. This is NOT a reentrant function: there is only one window pointer, and
  578. subsequent calls by ANY REXX process will affect the window.
  579.  
  580.     Calling sequence:
  581.  
  582.     result = PostMsg(x, y, strings, publicscreen)
  583.  
  584.     x             = x coordinate of top-left corner of requester.
  585.     y             = y coordinate of top-left corner of requester.
  586.         string        = A string which will be displayed above any gadgets.
  587.                         Any embedded '\' characters will be treated as a line
  588.                         break.
  589.     result        = 1 for success, 0 otherwise.
  590.         publicscreen  = Name of a public screen (optional).
  591.  
  592.     All arguments are optional, but the order is fixed. Therefore if
  593. only the second or third argument is specified, it needs to be prefixed by
  594. sufficient commas.
  595.     Examples:
  596.        Postmsg(50, 50, "This is line 1\This is line 2")
  597. will cause a window to appear with two lines of text. A subsequent call
  598.        Postmsg(50, 50, "\This is a new line 2")
  599. will cause the second line of the window to be replaced by the new text. The
  600. construct:
  601.        PostMsg(50, 50, " \")
  602. will erase the first line but leave the second one alone (notice the space).
  603.     If too few arguments are specified, this function will cause the
  604. window to be closed.
  605.     If 'publicscreen' is specified, the function will try to find the
  606. screen of that name. If it is set up properly, the requester will open on
  607. that screen. If not, the requester will appear on the Workbench. Under
  608. AmigaDOS 1.3, screenshare.library is used for this purpose. Under AmigaDOS
  609. 2.0 a "public" screen of that name will be looked for and if this fails,
  610. screenshare.library is used, if it is in libs:.
  611.  
  612. Getenv
  613. ======
  614.  
  615.     Calling sequence:
  616.  
  617.     result = Getenv(variable)
  618.  
  619.     variable   = Environment variable.
  620.         result     = The value of the environment variable.
  621.  
  622.     This function gets the value of an environment variable. If the
  623. variable does not exist, an empty string will be returned.
  624.  
  625. Setenv
  626. ======
  627.  
  628.     Calling sequence:
  629.  
  630.     result = Setenv(variable, valuestring)
  631.  
  632.     variable    = Environment variable.
  633.     valuestring = The new value for the environment variable.
  634.         result      = Always 1.
  635.  
  636.     This function (creates and) sets the environment variable to a
  637. a (new) value. If 'valuestring' is missing, the function will remove the
  638. environment variable.
  639.  
  640. ScreenToBack, ScreenToFront
  641. ===========================
  642.  
  643.     These functions depth arrange screens. If no argument is specified,
  644. the screen operated on is the Workbench screen. If the name of a public screen
  645. is specified, it will be affected.
  646.  
  647.     Calling sequence:
  648.  
  649.     result = screentoback(publicscreen)
  650.     result = screentofront(publicscreen)
  651.  
  652.         publicscreen  = Name of a public screen (optional).
  653.  
  654.     The argument is optional. If 'publicscreen' is specified, the
  655. function will try to find the screen of that name. If it is set up properly,
  656. the function will operate on that screen. If not, the function will operate on
  657. the Workbench. Under AmigaDOS 1.3, screenshare.library is used for this
  658. purpose. Under AmigaDOS 2.0 a "public" screen of that name will be looked for
  659. and if this fails, screenshare.library is used, if it is in libs:.
  660.  
  661. ScreenRows, ScreenCols, ScreenLace
  662. ==================================
  663.  
  664.     These functions retrieve info about screens. If no argument is
  665. specified, the screen operated on is the Workbench screen. If the name of
  666. a public screen is specified, it will be used.
  667.  
  668.     Calling sequences:
  669.  
  670.     result = ScreenRows(publicscreen)     /* return number of rows */
  671.     result = ScreenCols(publicscreen)     /* return number of columns */
  672.     result = ScreenLace(publicscreen)     /* return interlace */
  673.  
  674.         publicscreen  = Name of a public screen (optional)
  675.  
  676.     ScreenRows and ScreenCols retrieve the number of rows and columns in
  677. pixels. The function ScreenLace() returns 0 if the screen is not interlaced, and
  678. 1 if it is. The functions return -1 if the information could not be found, as is
  679. the case if the named public screen does not exist. Notice, that
  680. ScreenRows/Cols/Lace can be used to determine whether a public screen of a
  681. particular name exists.
  682.     The argument is optional. If 'publicscreen' is specified, the
  683. function will try to find the screen of that name. If it is set up properly,
  684. the function will operate on that screen. If not, the function will operate on
  685. the Workbench. Under AmigaDOS 1.3, screenshare.library is used for this
  686. purpose. Under AmigaDOS 2.0 a "public" screen of that name will be looked for
  687. and if this fails, screenshare.library is used, if it is in libs:.
  688.  
  689. ScreenColor
  690. ===========
  691.  
  692.     result = ScreenColor(publicscreen, n)          /* get color n     */
  693.  
  694.            or
  695.  
  696.         result = ScreenColor(publicscreen, n, R, G, B) /* get/set color n */
  697.  
  698.         publicscreen  = Name of a public screen.
  699.         n             = Number of color to retrieve/modify
  700.         R             = The amount of red in the new color   (0 - 15)
  701.         G             = The amount of green in the new color (0 - 15)
  702.         B             = The amount of blue in the new color  (0 - 15)
  703.  
  704.     ScreenColor retrieves the RGB values of the selected color in the
  705. format: <red><space><green><space><blue>, e.g:   15 0 0  for an all red
  706. screen. When the R G and B arguments are also given, the indicated color of
  707. the screen is modified to the new values. The *old* color values will be
  708. returned in result. ScreenColor only operates on public screens. The function
  709. will try to find the screen of that name. If it is set up properly, the
  710. function will operate on that screen. Under AmigaDOS 1.3, screenshare.library
  711. is used for this purpose. Under AmigaDOS 2.0 a "public" screen of that name
  712. will be looked for and if this fails, screenshare.library is used, if it is
  713. in libs:.
  714.  
  715. MoveScreen
  716. ==========
  717.  
  718.     result = MoveScreen(publicscreen, dx, dy)
  719.  
  720.         publicscreen  = Name of a public screen.
  721.         dx            = Amount to move it in X
  722.         dy            = Amount to move it in Y
  723.  
  724.         result        = 0 on failure. <xy> on success.
  725.  
  726.         MoveScreen moves an existing public screen by the specified amounts
  727. in x and y. Arguments that are left out are interpreted as 0. This function
  728. is of rather limited use in AmigaDOS 1.3: only movement in the y direction
  729. is supported, and negative values beyond the top of the screen are not allowed.
  730. If the function failed, 0 is returned, otherwise a string is returned with the
  731. actual position of the screen in the form <x> <space> <y>. Note that by leaving
  732. out both arguments, you will find the current position of the screen.
  733.     The function will try to find the screen of that name. If it is set
  734. up properly, the function will operate on that screen. Under AmigaDOS 1.3,
  735. screenshare.library is used for this purpose. Under AmigaDOS 2.0 a "public"
  736. screen of that name will be looked for and if this fails, screenshare.library
  737. is used, if it is in libs:.
  738.  
  739. OpenScreen, CloseScreen
  740. =======================
  741.  
  742.     These functions allow you to open public custom screens.
  743.  
  744.     Calling sequence:
  745.  
  746.     result = OpenScreen(topedge, depth, modes, defaulttitle, publicscreen,
  747.                             penlist, width, height, leftedge)
  748.     result = CloseScreen(publicscreen)
  749.  
  750.     topedge       = Y coordinate of top edge of the screen.
  751.     depth         = Number of bitplanes.
  752.     modes         = Viewmodes and type of screen. The currently supported
  753.                         viewmodes are "HIRES", "LACE", and "HAM". Currently
  754.                         supported types are "SCREENBEHIND", "TRUNCATE",
  755.                         "AUTOSCROLL" and "OVERSCAN".
  756.     defaulttitle  = Default title for the screen title bar.
  757.         publicscreen  = Name of the public screen
  758.         penlist       = String of the form <pen1><pen2>...<pen9>. Example:
  759.                         "121213102"   where:
  760.              |||||||||
  761.              ||||||||+-> HIGHLIGHTTEXTPEN special color text
  762.              |||||||+--> BACKGROUNDPEN    always color 0
  763.              ||||||+---> FILLTEXTPEN      text over FILLPEN
  764.              |||||+----> FILLPEN          active-window/selected-gadget fill
  765.              ||||+-----> SHADOWPEN        dark edge on 3D objects
  766.              |||+------> SHINEPEN         bright edge on 3D objects
  767.              ||+-------> TEXTPEN          text on background
  768.              |+--------> BLOCKPEN         Intuition block pen
  769.              +---------> DETAILPEN        Intuition detail pen
  770.         width         = Width of the screen
  771.         height        = Height of the screen
  772.         leftedge      = X-coordinate of left edge of the screen
  773.  
  774.     result        = 0 on failure, 1 on success.
  775.  
  776.     The screen name is required, therefore you must supply sufficient
  777. commas and a name for the public screen to be created/closed. With openscreen,
  778. leaving out any of the other arguments will cause defaults to be used. They are
  779. topedge = 0, depth = 2, modes = 0 (meaning LORES, no LACE), no default title,
  780. leftedge = 0, width and height the same as of the Workbench. This is equivalent
  781. to specifying 0 for all arguments (a depth of 0 is illegal and will be changed
  782. to 2). All created screens are CUSTOM screens under AmigaDOS 1.3 using
  783. "screenshare.library" and PUBLIC screens under AmigaDOS 2.0.
  784. The "TRUNCATE" screen type is not really an Intuition construct. It is only
  785. useful when "topedge" is non-zero: the screen will have the size of its visible
  786. portion at the time it is opened. Otherwise a full sized screen is opened,
  787. which is just displaced by "topedge". With rexxarplib version 2.8 and later,
  788. this option is really obsolete, since one can now specify the height of the
  789. screen.
  790.     ***NOTE: It is perfectly possible to apply closescreen() to another
  791. application's custom screen (if it is public, using the same conventions as
  792. used here). If you attempt this under AmigaDOS 1.3, a software failure is
  793. almost guaranteed. Only use closescreen() on screens you created using
  794. openscreen()!
  795.  
  796. ShowTitle
  797. =========
  798.  
  799.     This function shows or hides the title bar of a named public
  800. screen.
  801.  
  802.     Calling sequence:
  803.  
  804.     result = ShowTitle(publicscreen, yesno)
  805.  
  806.     publicscreen  = name of a publicscreen
  807.     yesno         = 0 or 1.
  808.  
  809.     If yesno is set to 1, the screen title of the named public screen
  810. will be shown, if set to 0, it will be hidden. The function will try to find
  811. the screen of that name. If it is set up properly, the function will operate
  812. on that screen. If not, the function will operate on the Workbench. Under
  813. AmigaDOS 1.3, screenshare.library is used for this purpose. Under AmigaDOS
  814. 2.0 a "public" screen of that name will be looked for and if this fails,
  815. screenshare.library is used, if it is in libs:. This function does not
  816. operate on the Workbench.
  817.  
  818. SETPUBSCREENMODE
  819. ================
  820.     This function sets a default public screen and sets its operating
  821. mode.
  822.  
  823.     Calling sequence:
  824.  
  825.     oldmode = SetPubScreenMode( name, modes )
  826.  
  827.     name    = A string containing the name of a public screen to be made
  828.               the default public screen.
  829.     modes    = The mode string.
  830.  
  831.     oldmode    = A numeric result indicating what the old global public screen
  832.               mode was.
  833.  
  834.     The modes value may be numeric in the range of 0..3, the return value
  835. from a previous call. It may also be a string containing zero, one, or both
  836. of the values "SHANGHI" and "POPPUBSCREEN". If the name string is an empty
  837. string the global pubscreen mode is set to 0 and a the Workbench screen is
  838. made the default.
  839.  
  840. GetDefPublicScreen
  841. ==================
  842.     This function returns a string containing the current default public
  843. screen name. If none is set it returns "Workbench". It takes no arguements.
  844.  
  845.     Calling sequence:
  846.  
  847.     result = GetDefPublicscreen()
  848.  
  849. FileList
  850. ========
  851.  
  852.     This function does ARP pattern matching. Given a pattern, it will
  853. return all files and/or directories matching the pattern.
  854.  
  855.     Calling sequence:
  856.  
  857.     number = FileList(pattern, stem, type, expand)
  858.  
  859.     pattern       = a search pattern using ARP wildcards.
  860.         stem          = the NAME of a stem variable to be created.
  861.         type          = D - directories only. F - files only.
  862.         expand        = E - expand full path name. N - remove path name
  863.                     not specified: don't expand, but don't remove either.
  864.  
  865.     number        = the number of files matching the pattern.
  866.  
  867.     When files with names matching the  pattern are found, a stem variable
  868. with the name given by 'stem' is created in the current Rexx context. It has
  869. fields 1, 2, ... , <number> containing the names of the files. The return value
  870. and also the stem variable's field 0 are equal to the number of files. The last
  871. two arguments are optional: with 'type', when an F is specified, only files are
  872. listed. When a D is specified only directories are listed. With 'expand', if an
  873. E is specified, the full path name is expanded. If an N is specified, any
  874. pathname part of the pattern will be removed. Example: a simple directory
  875. program looks like
  876.  
  877.     /* Directory program, list everything, with full path */
  878.     arg pattern
  879.     if pattern = "" then pattern = "*"
  880.     numfils = FileList(pattern, myfilelist, , E)
  881.     do i = 1 to numfils; say myfilelist.i; end
  882.     exit
  883.  
  884.  
  885. SendParsed
  886. ==========
  887.  
  888.     This function sends a filled in ARexx message to a port.
  889.  
  890.     Calling sequence:
  891.  
  892.     result = SendParsed(port, arg0, arg1, arg2, arg3, ..., arg13)
  893.  
  894.     port          = Portname to send ARexx message to.
  895.         argn          = Arguments of the message.
  896.  
  897. This function takes the 14 arguments, puts them in an ARexx message and sends
  898. it to the 'port'. Only the first argument (port) is required, though it is
  899. usually advisable to send at least an arg0. Note that ARexx messages can have
  900. 16 arguments, but the last two are unavailable because of how library calls
  901. like these are implemented.
  902.  
  903.  
  904. CreateHost
  905. ==========
  906.  
  907.     This function allows you to create a single window with gadgets, menus,
  908. text, graphics, etc. Of course, multiple copies of the function may be started
  909. up to create more windows, but each must have a unique 'controlport'. This
  910. function should be started up asynchronously, using runwsh, and one should wait
  911. for the 'controlport' to appear using e.g. WaitForPort.
  912.  
  913.     Calling sequence:
  914.  
  915.     runwsh 'call CreateHost(controlport, notifyport, publicscreen)'
  916.  
  917.     controlport   = Name of the message port this window should listen to.
  918.     notifyport    = Name of the message port that should be notified when
  919.                         an IDCMP event occurs.
  920.         publicscreen  = Name of a public screen (optional).
  921.  
  922.     When the function is first called, it will open a message port with the
  923. name given by "controlport". The function will then wait for commands coming in
  924. through this port. This may be accomplished using one of many intuition
  925. functions, as explained later. One of the first commands should be to open the
  926. associated window by calling OpenWindow (see later). It will then open a window
  927. as specified in the OpenWindow call. If any message arrives through the IDCMP of
  928. this window, a REXX message will be sent to the port specified as "notifyport"
  929. which either you should set up in your rexx macro for this purpose, or should be
  930. an otherwise existing rexx message port belonging to another process. In the
  931. case you set up your own port, make sure the message is replied to after having
  932. been  retrieved and examined. If the  notifyport does not exist, no message will
  933. be sent. The window can be closed by the rexx macro by calling the function
  934. CloseWindow (see later). On startup, the notify port is the same for all classes
  935. of messages. This can be changed using the SetNotify() function, see later.
  936.     The last argument is optional. If 'publicscreen' is specified, the
  937. function will try to find the screen of that name. If it is set up properly,
  938. the window will open on that screen. If not, the window will open on
  939. the Workbench. Under AmigaDOS 1.3, screenshare.library is used for this
  940. purpose. Under AmigaDOS 2.0 a "public" screen of that name will be looked for
  941. and if this fails, screenshare.library is used, if it is in libs:.
  942.  
  943. Supported Intuition (and other) functions with createhost
  944. =========================================================
  945.  
  946.     The following functions are implemented as CreateHost functions. The
  947. first argument is always the name of the control port of the host that is
  948. supposed to execute the command. A little secret: you can send commands
  949. *directly* to the controlport also by constructs like "Address controlport
  950. commandname". However, this only works for commands without further arguments.
  951. For example, from WShell, "address controlport CloseWindow" is equivalent to
  952. "call CloseWindow(controlport)". This can come in incredibly handy at times.
  953. For example, when you want command hosts to send message to themselves: you
  954. can tell a host to send IDCMP events of class CLOSEWINDOW to itself...
  955. Boggles the mind yet? Read on...
  956.  
  957.    call ActivateGadget(controlport, gadgetid)
  958.         Tries to activate a string gadget with id 'gadgetid'.
  959.  
  960.    call ActivateWindow(controlport)
  961.  
  962.    call AreaCircle(controlport, xcenter, ycenter, radius)
  963.  
  964.    call AreaDraw(controlport, x, y)
  965.  
  966.    call AreaEllipse(controlport, xcenter, ycenter, radius1, radius2)
  967.  
  968.    call AreaEnd(controlport, pen)
  969.         The "pen" argument is optional, and overrides the default, which is
  970.         that the area fill should be done using the current A pen (set with
  971.         SetAPen()). Pen values less than 256 have the usual meaning. Pen
  972.         values of 256 + i, where i = 0 through 15, cause the fill to be
  973.         performed using one of 16 standard fill patterns. Pen values of
  974.     512 + i, where i = 0 through 124, cause the fill to be performed
  975.     using one of 125 dithering patterns. The dithering patterns use pens
  976.     0 through 7. If these pens are set to black, white, red, green, blue,
  977.     cyan, magenta and yellow respectively, then the dithering patterns
  978.     form 125 different colors. To calculate a particular color index for
  979.         use as "pen", take the color's R G and B values, where R, G and B
  980.         are 0, 1, 2, 3 or 4,  and use:
  981.  
  982.         pen = R * 25 + G * 5 + B
  983.  
  984.         For example, full white would be (R = 4, G = 4, B = 4) and pen = 124.
  985.     A bluish grey would be (2, 2, 3), pen = 63.
  986.     Adding 1024 to the pen number causes AreaEnd to have no effect at all.
  987.     Adding 2048 to the pen number will cause the fill to have an outline
  988.     with the outline pen being the current A pen.
  989.     The SetOPen function no longer affects Area draws as of this revision.
  990.         Bug: For some reason, area circles and ellipses don't seem to get
  991.         outlines when requested.
  992.  
  993.    call AreaMove(controlport, x, y)
  994.  
  995.    call AddGadget(controlport, x, y, gadgetid, gadgettext, messagetext,
  996.                   hsize, flags)
  997.         If hsize is specified, this call creates a string gadget of that
  998.         horizontal size and gadgettext is the default string. If hsize is
  999.         not specified, this call creates an autosizing boolean gadget, where
  1000.         the text in gadgettext is displayed. In both cases, the string in
  1001.         messagetext is sent to controlport (see also under OpenWindow). As
  1002.         usual, the gadgettext for boolean gadgets may contain \ characters
  1003.         to cause multiple lines of text (See e.g. PostMsg()). Under 2.0,
  1004.         a flag can be specified for string gadgets: RIDGEBORDER. This will
  1005.         cause the gadget to be displayed in the "2.0" style. Since this style
  1006.         of gadget is a little different in size and location than non-ridge
  1007.         border gadgets, the default is the usual gadget border under 1.3 and
  1008.         a "recessed" gagdet under 2.0.
  1009.  
  1010.    call AddItem(controlport, itemname, message, commandchar, mutualexclude, flag)
  1011.         Add a new item with name 'itemname'. Optionally, you may specify a
  1012.         command key abbreviation (right-Amiga 'commandchar') and a mutual exclude
  1013.         mask. See Intuition manual. A special value of the mutual exclude mask
  1014.         is -1: this means that the item will be toggle selectable. If the flag
  1015.         argument is "SAMELINE", the item will be on the same line as the previous
  1016.         item, otherwise, or if the argument is not present, it will be on the
  1017.         next line.
  1018.         See also AddMenu(), AddSubItem(), RemoveMenu(), SetItem().
  1019.  
  1020.    call AddMenu(controlport, menuname)
  1021.         Add a new menu with name 'menuname'. See also AddItem(), AddSubItem(),
  1022.         RemoveMenu(), SetItem().
  1023.  
  1024.    call AddSubItem(controlport,itemname,message,commandchar,mutualexclude,flag)
  1025.         Add a new subitem with name 'itemname'. Optionally, you may specify a
  1026.         command key abbreviation (right-Amiga 'commandchar') and a mutual exclude
  1027.         mask. See Intuition manual. A special value of the mutual exclude mask
  1028.         is -1: this means that the item will be toggle selectable. If the flag
  1029.         argument is "SAMELINE", the item will be on the same line as the previous
  1030.         item, otherwise, or if the argument is not present, it will be on the
  1031.         next line.
  1032.         See also AddMenu(), AddItem(), RemoveMenu(), SetItem().
  1033.  
  1034.    call BackFill(controlport)
  1035.         This is not an intuition function. See OpenWindow().
  1036.  
  1037.    call CloseWindow(controlport, flag)
  1038.         This function closes the window and deallocates all resources. The 'flag'
  1039.         argument is optional. If present, and if the flag is equal to "CONTINUE",
  1040.         the host will remain active. Otherwise, the host will exit.
  1041.  
  1042.    call Draw(controlport, x, y)
  1043.  
  1044.    call DrawCircle(controlport, xcenter, ycenter, radius)
  1045.  
  1046.    call DrawEllipse(controlport, xcenter, ycenter, radius1, radius2)
  1047.  
  1048.    call Exit(controlport)
  1049.         This function closes the window, deallocates all resources and causes
  1050.         the host to exit. Exit(), Quit() and Stop() are identical.
  1051.  
  1052.    call Flood(controlport, mode, x, y)
  1053.         If mode is 0, the flood continues until pixels of the outline pen
  1054.         color are found. If the mode is 1, the flood continues until pixels
  1055.         of a different color than the pixel at x, y are found.
  1056.  
  1057.    call RemoveMenu(controlport)
  1058.         Gets rid of any attached menu.
  1059.  
  1060.    call IFFImage(controlport, filename, x, y, width, height, flag)
  1061.         Displays a chunk of size 'width', 'height' of an IFF ILBM file named
  1062.         'filename' at x, y in the window. If x, y, width, and/or height are
  1063.         omitted, suitable defaults are chosen. The colormap of the IFF file,
  1064.         if any, is NOT used on the Workbench, but IS used on custom screens.
  1065.         The 'flag' option can be set to 'NOCOLOR' (N is sufficient) to prevent
  1066.         modifying the custom screen's colors.
  1067.  
  1068.    call ModifyHost(controlport, IDCMPclass, messagestring)
  1069.         This function allows you to set the message string that is sent to
  1070.         the notifyport for a particular class of IDCMP events. See OpenWindow.
  1071.  
  1072.    call Move(controlport, x, y)
  1073.  
  1074.    call OpenWindow(controlport, leftedge, topedge, width, height,
  1075.                                 idcmp, flags, title)
  1076.         width and height may be set to 0 to get the maximum size of the window.
  1077.         idcmp is a string that specifies the IDCMP for the window. Supported are:
  1078.  
  1079.            IDCMP message    |  default arg[0]
  1080.         --------------------+-------------------
  1081.           "CLOSEWINDOW"     |  "%l"
  1082.           "MOUSEBUTTONS"    |  "%l"
  1083.           "GADGETUP"        |  <its string>
  1084.           "GADGETDOWN"      |  <its string>
  1085.           "MENUPICK"        |  "%l"
  1086.           "NEWSIZE"         |  "%l"
  1087.           "VANILLAKEY"      |  "%l"
  1088.           "RAWKEY"          |  "%l"
  1089.           "NEWPREFS"        |  "%l"
  1090.           "DISKINSERTED"    |  "%l"
  1091.           "DISKREMOVED"     |  "%l"
  1092.           "ACTIVEWINDOW"    |  "%l"
  1093.           "INACTIVEWINDOW"  |  "%l"
  1094.           "REFRESHWINDOW"   |  "%l"
  1095.           "MOUSEMOVE"       |  "%l"
  1096.           "DELTAMOVE"       |  "%l"
  1097.  
  1098.         Any number of these may be specified in the OpenWindow call, by conca-
  1099.         tenation. When any of these messages arrives at the IDCMP, a REXX
  1100.         message is created with a particular string in Arg[0]. This string is
  1101.         by default the one given in the table above, after substitution has
  1102.         taken place for any two-character sequence starting with '%'.
  1103.         The following substitutions will be made:
  1104.  
  1105.         Sequence: | Typical Use: |     Meaning:
  1106.         ----------+--------------+---------------
  1107.             %%    |              | A single % sign
  1108.             %a    | Vanillakeys  | 'Code' is interpreted as an ASCII character.
  1109.             %b    | Buttons      | SELECTDOWN, SELECTUP, MENUDOWN, MENUUP.
  1110.             %c    |              | 'Code' is given as an integer.
  1111.             %d    | Gadgets      | the gadget id.
  1112.             %e    | Window       | the TopEdge of the window
  1113.             %f    | Window       | the LeftEdge of the window
  1114.             %g    | Gadgets      | the string inside a string gadget goes here.
  1115.             %h    | Newsize      | the window height.
  1116.             %i    | Menus        | the item number.
  1117.             %l    | Any          | the name of the IDCMP class.
  1118.             %m    | Menus        | the menu number.
  1119.             %q    |              | 'Qualifier' is given as an integer.
  1120.             %s    | Menus        | the sub-item number.
  1121.             %t    | Time         | the number of seconds since January 1 1980.
  1122.             %w    | Newsize      | the window width.
  1123.             %x    | Mouse        | the X position of the mouse pointer.
  1124.             %y    | Mouse        | the Y position of the mouse pointer.
  1125.           %0-%15  |              | which Arg to use.
  1126.  
  1127.         For example, if the message string of some gadget is
  1128.  
  1129.             "Mouse is %x, %y%3gadget string is %g"
  1130.  
  1131.         the following might be sent to the notifyport in Arg[0] when someone
  1132.         hits return in that gadget, after typing "This is a test":
  1133.  
  1134.             Mouse is 320, 200
  1135.  
  1136.         while Arg[3] of the Rexx message would contain the string:
  1137.  
  1138.             gadget string is This is a test
  1139.  
  1140.         The default string for non-gadgets/menus is "%l", which means that they
  1141.         only report their name. For example, if one would click in the window,
  1142.         one would only receive a message with "MOUSEBUTTONS" in Arg[0]. However,
  1143.         all arguments of the message that will be sent to the notifyport may be
  1144.         changed using the ModifyHost() call, see there. Any of the escape
  1145.         sequences above may be used in any string. Obviously, sometimes
  1146.         particular sequences may not be very appropriate for certain uses.
  1147.  
  1148.         'flags' specifies the various window flags. Currently supported are:
  1149.         "WINDOWCLOSE", "WINDOWSIZING" (and "SIZEBRIGHT", "SIZEBBOTTOM"),
  1150.         "WINDOWDEPTH", "WINDOWDRAG", "BORDERLESS", "ACTIVATE", "BACKDROP",
  1151.         "NOCAREREFRESH", and "REPORTMOUSE".  A special flag can be set:
  1152.         "BACKFILL". It implies a call to BackFill() after opening the window.
  1153.         It sets the window's background to the current requester-style
  1154.         background color.
  1155.  
  1156.    call Quit(controlport)
  1157.         This function closes the window, deallocates all resources and causes
  1158.         the host to exit. Exit(), Quit() and Stop() are identical.
  1159.  
  1160.    call ReadGadget(controlport, gadgetid)
  1161.         This function will cause the gadget 'gadgetid' to send its message
  1162.         text (after substitutions, of course).
  1163.  
  1164.    call ReadHost(controlport, notifyport, messagetext)
  1165.         This function will cause the message text (after substitutions, of
  1166.         course) to be sent to the notifyport.
  1167.  
  1168.    call RectFill(controlport, xmin, ymin, xmax, ymax)
  1169.  
  1170.    call RefreshGadgets(controlport)
  1171.  
  1172.    call RemoveGadget(controlport, gadgetid)
  1173.  
  1174.    call SetAPen(controlport, pennumber)
  1175.  
  1176.    call SetBPen(controlport, pennumber)
  1177.  
  1178.    call SetDrMd(controlport, mode)
  1179.         mode can be any of JAM1, JAM2, INVERSVID or COMPLEMENT.
  1180.  
  1181.    call SetDrPt(controlport, pattern)
  1182.         pattern is interpreted as a long integer of which the bits form the
  1183.         pattern.
  1184.  
  1185.    call SetFont(controlport, FontName, FontSize, FontStyle, FontFlags, XSize)
  1186.         Change the font to the one specified. If the font doesn't exist or
  1187.         doesn't exist in the specified FontSize, the function does
  1188.         nothing. If the font does exist, the closest match FontStyle and
  1189.         FontFlags font is returned that is currently in memory or if it is
  1190.         not in memory, that is currently in fonts:. If XSize is specified,
  1191.         the font will be rejected also if the horizontal size doesn't match.
  1192.         FontStyle bits:
  1193.  
  1194.               none = Normal
  1195.               1    = Underlined
  1196.               2    = Bold
  1197.               4    = Italic
  1198.               8    = Extended face (wider than normal)
  1199.               64   = Color font
  1200.  
  1201.         Note that the function calls SetSoftStyle() internally to fake any
  1202.         of the attributes if the closest font doesn't match the requirements.
  1203.         FontFlag bits:
  1204.  
  1205.               1    = Font is in ROM
  1206.               2    = Font is from diskfont.library
  1207.               4    = Font is reverse path (left to right)
  1208.               8    = designed for hires non-interlaced
  1209.               16   = designed for lores interlaced
  1210.               32   = Font is proportional
  1211.               64   = Font is designed
  1212.  
  1213.         This function requires that diskfont.library is present in libs:.
  1214.  
  1215.    call SetGadget(controlport, gadgetid, action)
  1216.         Given a gadget id, perform action on the gadget. Supported are ON and
  1217.         OFF, to set or clear the highlighting state of the gadget.
  1218.  
  1219.    call SetItem(controlport, menunumber, itemnuber, subitemnumber, action)
  1220.         Given menu, item (and optionally subitem) numbers, perform action on
  1221.         the menu item. Supported are ON and OFF, to set or clear the check mark.
  1222.         Remember that menu, item and subitem numbers start from 0.
  1223.  
  1224.    call SetNotify(controlport, IDCMPclass, newnotifyport)
  1225.         This function allows you to change the name of the NotifyPort that
  1226.         message strings are sent to for a particular class of IDCMP events.
  1227.  
  1228.    call SetReqColor(controlport, pentype, colornumber)
  1229.         This function allows you to change the color number assigned to
  1230.         one of the various pentypes. Currently the pentypes are: BLOCKPEN,
  1231.         DETAILPEN, BACKGROUNDPEN, PROMPTPEN, BOXPEN, SHADOWPEN, OKAYPEN,
  1232.         and CANCELPEN.
  1233.  
  1234.    call SetOPen(controlport, pennumber)
  1235.         SetOpen is mostly obsolete, see AreaEnd().
  1236.  
  1237.    call SetRGB4(controlport, pennumber, red, green, blue)
  1238.         red, green and blue are values for the RGB content of the color to be
  1239.         assigned to the pen. The values are taken mod 16.
  1240.  
  1241.    call Stop(controlport)
  1242.         This function closes the window, deallocates all resources and causes
  1243.         the host to exit. Exit(), Quit() and Stop() are identical.
  1244.  
  1245.    call Text(controlport, string)
  1246.  
  1247.    call WindowText(controlport, text)
  1248.         The string in text may contain \'s to indicate multiple lines of text.
  1249.  
  1250.    call WindowToBack(controlport)
  1251.  
  1252.    call WindowToFront(controlport)
  1253.  
  1254.    call WritePixel(controlport, x, y)
  1255.  
  1256.  
  1257.  
  1258.  
  1259.